Sapphire Yours - Internal Documentation
For all that are willing to create their own artworks or soundsets, here is a brief description of the file format we use for these kind of data.Artwork
Graphics files for Sapphire Yours
All the graphics the game needs is located in the 'art\' directory. There are a few files that the game uses for all levels and the main menu and there can also be various subdirectories, each containing the graphics for one artwork.The directory 'art\default\' contains all animation sequences and pictures needed for all levels using the "default" artwork. Other artworks can be defined by simply creating a new directory and adding all pictures and animations that should be different to the default (the game tries to load the graphic from the desired artwork directory first, but falls back to the default if such a file is not found there)
Graphics format
Sapphire Yours uses standard '.bmp' files to store graphical data, but in the current version the game can only read non-compressed palettized graphics (no true-color).The size of the pictures for the game is always 60x60 pixel. There are also many files that contain a whole sequence of pictures (different animation steps that belong to the same action). In this case the pictures are always located directly next to each other and the ordering for animations is always right to left (this leading to the final picture being the one to the total left).
If the graphics in the .bmp is bigger than 60 n x 60 the exceeding pixels are merrily ignored.
Note: The number of steps one animation sequence has is determined only by the horizontal size of the graphic - so simply adding more animation steps to the graphics will result in smoother animation during the game.
Palette
The game currently runs in a 256 color mode using a color palette. This palette will be loaded from the "palette.bmp" file in the '\art' directory. The colors of all other graphic files will then be mapped to this palette.Transparency color
Since the ".bmp" format does not allow to define a transparency region directly, the game needs a way to decide which color in a picture should be treated as "transparent".Sapphire Yours just uses the color of the top right corner in the graphics file as the transparency color. In most cases (Stones,Gems,Miner,etc...) this works perfectly well since this objects do not reach the top right corner with their visible graphics.
But there are some cases, where the top right pixel should also be visible (earth, safes). To do this, just add an extra column of pixels to the total right of the graphics file that contain the transparency color. As I have said earlier, exceeding pixel in the graphic file will be ignored and not taken for the picture graphics, but nevertheless the rightmost pixel (of the file, not the pictures inside) will indeed be considered to determine the transparency color.
Soundsets
All sounds needed for Sapphire Yours:Each soundset consists of a set of .wav - files that must be located in the directory "sound\[soundset]\" (being [soundset] the name of the set)
For every sound file that can not be found in the sound set, the system tries to use the appropriate file from the default set.
| Filename | Description |
|---|---|
| walk.wav | Miner walking |
| dig.wav | Miner digging |
| win.wav | Sound for a finished game |
| lose.wav | Signal sound if too much gems have been destroyed |
| die.wav | Miner dying |
| push.wav | Miner pushing a stone |
| pushbomb.wav | Miner pushing a bomb |
| pushbag.wav | Miner pushing a bag |
| pushbox.wav | Miner pushing a box |
| cushion.wav | Something falling on a cushion |
| pcushion.wav | Miner pushing a cushion |
| grabemld.wav | Miner picking up an emerald |
| grabsphr.wav | Miner picking up a saphire |
| grabruby.wav | Miner pickung up a ruby |
| grabbomb.wav | Miner picking up a timebomb |
| grabkey.wav | Miner picking up a key |
| setbomb.wav | Miner setting a timebomb |
| usedoor.wav | Miner going through a door (not the exit) |
| stnroll.wav | Stone rolling from a round surface |
| stnfall.wav | Stone falling on a soft ground |
| stnhard.wav | Stone falling on a hard ground |
| stnconv.wav | Stone being converted to an emerald |
| emldroll.wav | Emerald rolling from a round surface |
| emldfall.wav | Emerald falling to the ground |
| emldconv.wav | Emerald being converted to a saphire |
| sphrroll.wav | Saphire rolling from a round surface |
| sphrfall.wav | Saphire falling to the ground |
| sphrbrk.wav | Saphire being crushed by a stone |
| sphrconv.wav | Saphire being converted to a stone |
| rubyroll.wav | Ruby rolling from a round surface |
| rubyfall.wav | Ruby falling on the ground |
| rubyconv.wav | Ruby being converted to a bag |
| bagroll.wav | Bag rolling from a round surface |
| bagfall.wav | Bag falling to the ground |
| bagopen.wav | Bag being opened by stone |
| bagconv.wav | Bag being converted to a ruby |
| bombroll.wav | Bomb rolling from a round surface |
| exitopen.wav | Exit opening |
| exitclos.wav | Exit closing behind a miner |
| bombtick.wav | Timebomb ticking |
| blastvipwav | Sound of a Very Important Piece getting blasted |
| explode.wav | Explosion |
| swamp.wav | Swamp trying to produce a drop |
| drop.wav | Swamp drop hitting the ground |
| lorry.wav | Lorry being somewhere in the vicinity |
| yamyam.wav | Characteristic sound of the yamyam-monster |
| acid.wav | Something being dissolved in acid |
| clock.wav | Clock striking at the end of the available time |
| laser.wav | Laser beam |
| wheel.wav | Sound of robot-attraction wheel |
| robot.wav | Robot moving |
Level file format
The levels in Sapphire Yours are stored in the directories 'levels\xxxx\' as simple ASCII-text. These directories will be scanned at startup and all available files will show up as levels you can select and play. You can create own levels with Syle or by using your favourite text-editor. (Sending sapphire-yours-levels by e-mail and such providing your friends with a tricky riddle is quite fun...)Every level has to be stored in a file named {name}>.lev somewhere in the directory tree beneath 'levels\' in order for the game to find it.
Each file consists of a sequence of commands (each command starts in a seperate line) with attributes.
Valid commands (and their default values) are:
| n {longname} | long name of the level | |
| (0) | D {difficulty} | number from 0 to 10 giving the difficulty of this level |
| (all) | e {num} | number of emeralds to collect |
| (unlimited) | E {num} | number of emeralds (or other valuables) that may be destroyed before a "level impossible" warning is displayed. |
| (unlimited) | T {turns} | time in turns to complete the level |
| (30) | s {prob} | probability to spread the swamp (the lower the number, the faster the spreading. But: a value of 0 means no spreading at all) |
| (4) | p {prob} | probability that pushing a stone/bomb/bag will work (the higher the number, the more often. But: a value of 0 makes the pushing to work always) |
| (5) | d {intervall} | speed of the stone dispenser |
| (3) | o {prob} | probability for the robots to move |
| (30) | w {time} | time period the wheel will continue running after being activated |
| Y | Turn off the YAM-YAM-Sound of the yamyam-beasts (there are some levels where the non-stop-yamyaming would be quite annoying) | |
| L | Turn off the laser-sound and the explosions | |
| A {artwork} | artwork to be used for this level (subdirectory of 'art\') | |
| S {soundset} | sounds to be used for this level (subdirectory of "sound\") | |
| M {startpos} {midifile} | song to be played in this level, and the position where to start playing it. | |
| N {longname} | The level that will be started after successful completion of this one (to build level-series) You may also reference levels that do not exist yet, the command will be ignored in such a case. | |
| i {text line} | A line of informational text for this level | |
| a {name} | Name of the designer (author) of the level | |
| f {name} | Name of the player who was the first to finish the level | |
| m {width} {height} | ||
| {map} | dimension and map of the level. The actual map-data starts in a new line immediately after the dimension-info and consists of: {height} lines containing {width} map-characters each. Maximum value for width and height is 126. | |
| y {data} | Explosion remainders for the yam-yam-beasts. The data should contain 9 map-characters that will then be arranged to a 3*3 square. | |
| R {data} | Will be generated by Sapphire Yours to store demo-mode-information. | |
| 0 {flags} | Flags for the demo | |
| 1 {demo name} | Textual description of the demo | |
| 2 {data} | Demo-data in V1.0 format |
With the exception of 'm' all of those commands are optional.
Map data elements:
' ' or '~' | air |
. | earth |
s | quicksand |
S | quicksand with stone inside |
# | wall |
: | glass wall |
i | invisible wall (can be blasted) |
+ | stone wall (can be blasted) |
| | stone wall with rounded top |
& | stone wall with embedded emerald |
* | emerald |
$ | sapphire |
( | ruby |
0 | stone |
@ | bag |
Q | bomb |
E | exit |
% | swamp |
/ | drop |
! | timebomb |
? | timebomb already ticking |
" | box of 10 timebombs |
c | converter |
[ | safe |
_ | cushion |
d | stone dispenser |
a | acid |
b,r,g,y | blue,red,green,yellow key |
B,R,G,Y | blue,red,green,yellow door |
5,6,7,8 | lorry moving left,up,right,down |
h,u,k,j | bug moving left,up,right,down |
<,^,>,V | yam-yam beast moving left,up,right,down |
o | robot |
w | wheel |
1 | player 1 (you) |
2 | player 2 (in 2-player-levels) |
A trivial level would look like:
m 2 1 1EThis is probably the shortest solveable level...
Sapphire Yours Homepage